% main=manual.tex

\section{Installation and Prerequisites}

\subsection{Licensing}

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

A copy of the GNU General Public License can be found in the package file
%
\begin{verbatim}
doc/latex/pgfplots/gpl-3.0.txt
\end{verbatim}
%
You may also visit~\url{http://www.gnu.org/licenses}.


\subsection{Prerequisites}

\PGFPlots{} requires \PGF{}. You should generally use the most recent stable
version of \PGF{}. \PGFPlots{} is used with
%
\input pgfplots.preliminaries.compatcurrent.tmp
%
\noindent in your preamble (see Section~\ref{sec:tex:dialects} for information
about how to use it with Con\TeX{}t and plain \TeX{}).

The |compat=|\meta{yourversion} entry should be added to activate new features,
see the documentation of the |compat| key for more details.


%\subsection{Installation}

There are several ways how to teach \TeX{} where to find the files. Choose the
option which fits your needs best.


\subsection{Installation in Windows}

Windows users often use MiK\TeX{} which downloads the latest stable package
versions automatically. You do not need to install anything manually here.

If you want to install or more recent version of \PGFPlots{} than the one
shipped with MiK\TeX{}, you can proceed as follows. MiK\TeX{} provides a
feature to install packages locally in its own \TeX{} Directory Structure
(TDS). The basic idea is to unzip \PGFPlots{} in a directory of your choice and
configure the MiK\TeX{} Package Manager to use this specific directory with
higher priority than its default paths. If you want to do this, start the
MiK\TeX{} Settings using ``Start $\gg$ Programs $\gg$ MiK\TeX{} $\gg$
Settings''. There, use the ``Roots'' menu section. It contains the MiK\TeX{}
Package directory as initial configuration. Use ``Add'' to select the directory
in which the unzipped \PGFPlots{} tree resides. Then, move the newly added path
to the list's top using the ``Up'' button. Then press ``Ok''. For MiK\TeX{}
2.8, you may need to uncheck the ``Show MiK\TeX{}-maintained root directories''
button to see the newly installed path.

MiK\TeX{} complains if the provided directory is not TDS conform (see
Section~\ref{pgfplots:tds} for details), so you can't provide a wrong directory
here. This method does also work for other packages, but some packages may need
some directory restructuring before MiK\TeX{} accepts them.


\subsection{Installation of Linux Packages}

Typically, \PGFPlots{} can be installed using the \TeX{} package manager. A
common distribution is \TeX{}Live. In this case you can write
%
\begin{codeexample}[code only]
sudo tlmgr install pgfplots
\end{codeexample}
%
\noindent in order to install \PGFPlots{}.


\subsection{Installation in Any Directory -- the \texttt{TEXINPUTS} Variable}

You can simply install \PGFPlots{} anywhere on your hard drive, for example
into
%
\begin{verbatim}
/foo/bar/pgfplots.
\end{verbatim}
%
Then, you set the \texttt{TEXINPUTS} variable to
%
\begin{verbatim}
TEXINPUTS=/foo/bar/pgfplots/tex//:
\end{verbatim}
%
The trailing~`\texttt{:}' tells \TeX{} to check the default search paths after
\lstinline!/foo/bar/pgfplots!. The double slash~`\texttt{//}' tells \TeX{} to
search all subdirectories.

If the \texttt{TEXINPUTS} variable already contains something, you can append
the line above to the existing \texttt{TEXINPUTS} content.

Furthermore, you should set |TEXDOCS| as well,
%
\begin{verbatim}
TEXDOCS=/foo/bar/pgfplots/doc//:
\end{verbatim}
%
so that the \TeX{} documentation system finds the files |pgfplots.pdf| and
|pgfplotstable.pdf| (on some systems, it is then enough to use
|texdoc pgfplots|).

Starting with \PGFPlots{} 1.12, you may also need to adopt \texttt{LUAINPUTS}:
%
\begin{verbatim}
LUAINPUTS=/foo/bar/pgfplots//:
\end{verbatim}
%
should usually do the job.

Please refer to your operating systems manual for how to set environment
variables.


\subsection{Installation Into a Local TDS Compliant \texttt{texmf}-Directory}
\label{pgfplots:tds}

\PGFPlots{} comes in a ``\TeX{} Directory Structure'' (TDS) conforming
directory structure, so you can simply unpack the files into a directory which
is searched by \TeX{} automatically. Such directories are |~/texmf| on Linux
systems, for example.

Copy \PGFPlots{} to a local \texttt{texmf} directory like \lstinline!~/texmf!.
You need at least the \PGFPlots{} directories |tex/generic/pgfplots| and
|tex/latex/pgfplots|. Then, run \lstinline!texhash! (or some equivalent
path-updating command specific to your \TeX{} distribution).

The TDS consists of several sub directories which are searched separately,
depending on what has been requested: the sub directories
|doc/latex/|\meta{package} are used for (\LaTeX{}) documentation, the
sub-directories |doc/generic/|\meta{package} for documentation which apply to
\LaTeX{} and other \TeX{} dialects (like plain \TeX{} and Con\TeX{}t which have
their own, respective sub-directories) as well.

Similarly, the |tex/latex/|\meta{package} sub-directories are searched whenever
\LaTeX{} packages are requested. The |tex/generic/|\meta{package}
sub-directories are searched for packages which work for \LaTeX{} \emph{and}
other \TeX{} dialects.

Do not forget to run \lstinline!texhash!.

\subsection{Installation If Everything Else Fails\ldots}

If \TeX{} still doesn't find your files, you can copy all \lstinline!.sty! and
all |.code.tex| files (perhaps all |.def| files as well) into your current
project's working directory. In fact, you need everything which is in the
|tex/latex/pgfplots| and |tex/generic/pgfplots| sub directories.

Please refer to \url{http://www.ctan.org/installationadvice/} for more
information about package installation.


\section{Troubleshooting -- Error Messages}

This section discusses some problems which may occur when using \PGFPlots{}.
Some of the error messages are shown in the index, take a look at the end of
this manual (under ``Errors'').


\subsection{Problems with available Dimen registers}

To avoid problems with the many required \TeX{} registers for \PGF{} and
\PGFPlots{}, you may want to include
%
\begin{verbatim}
\usepackage{etex}
\end{verbatim}
%
as first package. This avoids problems with ``no room for a new
dimen''\index{Error Messages!No room for a new dimen} in most cases. It should
work with any modern installation of \TeX{} (it activates the
$\varepsilon$-\TeX{} extensions).


\subsection{Dimension Too Large Errors}

The core mathematical engine of \PGF{} relies on \TeX{} registers to perform
fast arithmetics. To compute $50+299$, it actually computes |50pt+299pt| and
strips the |pt| suffix of the result. Since \TeX{} registers can only contain
numbers up to $\pm 16384$, overflow error messages like ``Dimension too large''
occur if the result leaves the allowed range. Normally, this should never
happen -- \PGFPlots{} uses a floating point unit with data range $\pm 10^{324}$
and performs all mappings automatically. However, there are some cases where
this fails. Some of these cases are:
%
\begin{enumerate}
    \item The axis range (for example, for $x$) becomes \emph{relatively}
        small. It's no matter if you have absolutely small ranges like
        $[10^{-17},10^{-16}]$. But if you have an axis range like
        $[1.99999999,2]$, where a lot of significant digits are necessary,
        this may be problematic.

        I guess I can't help here: you may need to prepare the data somehow
        before \PGFPlots{} processes it.
    \item This may happen as well if you only view a very small portion of
        the data range.

        This happens, for example, if your input data ranges from $x\in
        [0,10^6]$, and you say |xmax=10|.

        Consider using the |restrict x to domain*=|\meta{min}|:|\meta{max}
        key in such a case, where the \meta{min} and \meta{max} should be
        (say) four times of your axis limits (see
        page~\pageref{key:restrict:x:to:domain} for details).
    \item The |axis equal| key will be confused if $x$ and $y$ have a very
        different scale.
    \item You may have found a bug -- please contact the developers.
\end{enumerate}


\subsection{Restrictions for DVI Viewers and \texttt{dvipdfm}}
\label{sec:drivers}

\PGF{} is compatible with
%
\begin{itemize}
    \item \lstinline!latex!/\lstinline!dvips!,
    \item \lstinline!latex!/\lstinline!dvipdfm!,
    \item \lstinline!pdflatex!,
    \item $\vdots$
\end{itemize}
%
However, there are some restrictions: I don't know any DVI viewer which is
capable of viewing the output of \PGF{} (and therefor \PGFPlots{} as well).
After all, DVI has never been designed to draw something different than text
and horizontal/vertical lines. You will need to view the postscript file or the
PDF file.

Then, the DVI/PDF combination doesn't support all types of shadings (for
example, the |shader=interp| is only available for |dvips|, |pdftex|,
|dvipdfmx|, and |xetex| drivers).

Furthermore, \PGF{} needs to know a \emph{driver} so that the DVI file can be
converted to the desired output. Depending on your system, you need the
following options:
%
\begin{itemize}
    \item \lstinline!latex!/\lstinline!dvips! does not need anything special
        because \lstinline!dvips! is the default driver if you invoke
        \lstinline!latex!.
    \item \lstinline!pdflatex! will also work directly because
        \lstinline!pdflatex! will be detected automatically.
    \item \lstinline!lualatex! will also be detected automatically.
    \item \lstinline!latex!/\lstinline!dvipdfm! requires to use
        %
\begin{verbatim}
\def\pgfsysdriver{pgfsys-dvipdfm.def}
%\def\pgfsysdriver{pgfsys-pdftex.def}
%\def\pgfsysdriver{pgfsys-dvips.def}
%\def\pgfsysdriver{pgfsys-dvipdfmx.def}
%\def\pgfsysdriver{pgfsys-xetex.def}
%\def\pgfsysdriver{pgfsys-luatex.def}
\usepackage{pgfplots}.
\end{verbatim}
        %
        The uncommented commands could be used to set other drivers
        explicitly.
\end{itemize}
%
Please read the corresponding sections in~\cite[Sections~7.2.1 and 7.2.2]{tikz}
if you have further questions. These sections also contain limitations of
particular drivers.

The choice which won't produce any problems at all is |pdflatex|.


\subsection{Problems with \TeX's Memory Capacities}

\PGFPlots{} can handle small up to medium sized plots. However, \TeX{} has
never been designed for data plots -- you will eventually face the problem of
small memory capacities. See Section~\ref{sec:pgfplots:optimization} for how to
enlarge them.


\subsection{Problems with Language Settings and Active Characters}

Both \PGF{} and \PGFPlots{} use a lot of active characters -- which may lead to
incompatibilities with other packages which define active characters.
Compatibility is better than in earlier versions, but may still be an issue.
The manual compiles with the |babel| package for English and French, the
|german| package does also work. If you experience any trouble, let me know.
Sometimes it may work to disable active characters temporarily (|babel|
provides such a command).


\subsection{Other Problems}

Please read the mailing list at
\url{http://sourceforge.net/projects/pgfplots/support}. Perhaps someone has
also encountered your problem before, and maybe he came up with a solution.

Please write a note on the mailing list if you have a different problem. In
case it is necessary to contact the authors directly, consider the addresses
shown on the title page of this document.
